数据管理DMS的数据服务是将您在DMS上管控的数据以API的形式快速对外输出的功能,本文将介绍如何新增、发布、测试与调用API。
前提条件
已开通API网关。
准备工作
本示例已提前创建student_courses
表,并插入部分测试数据,SQL语句如下:
/** 创建表 **/
CREATE TABLE `student_courses` (
`id` BIGINT(20) UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
`student_id` BIGINT(20) DEFAULT NULL COMMENT '学生ID',
`course_id` BIGINT(20) DEFAULT NULL COMMENT '课程ID',
`start_time` DATETIME DEFAULT NULL COMMENT '创建时间',
`score` int(11) DEFAULT NULL COMMENT '考试成绩',
KEY `idx_student_course` (`student_id`,`course_id`),
KEY `idx_student_time` (`student_id`,`start_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='数据服务测试表';
/** 插入数据 **/
INSERT INTO `student_courses` VALUES (1,1,1,'2020-11-24 11:19:54',78);
INSERT INTO `student_courses` VALUES (2,1,2,'2020-11-24 05:51:36',68);
INSERT INTO `student_courses` VALUES (3,1,3,'2020-11-24 05:28:08',60);
INSERT INTO `student_courses` VALUES (4,2,1,'2020-11-24 07:21:17',67);
INSERT INTO `student_courses` VALUES (5,2,2,'2020-11-24 02:07:52',91);
INSERT INTO `student_courses` VALUES (6,2,3,'2020-11-24 10:35:35',94);
INSERT INTO `student_courses` VALUES (7,3,1,'2020-11-24 03:19:03',53);
INSERT INTO `student_courses` VALUES (8,3,2,'2020-11-24 08:19:18',94);
INSERT INTO `student_courses` VALUES (9,3,3,'2020-11-24 02:04:17',89);
步骤一:新增并发布API
- 登录数据管理DMS 5.0。
在顶部菜单栏中,选择 。
说明若您使用的是极简模式的控制台,请单击控制台左上角的图标,选择
。进入数据服务页面后,在左侧导航栏,单击API开发。
进入API管理页面,单击右上角的新增API。
配置信息。
API的属性包含属性配置、执行配置、请求参数、返回参数,共4个部分,由于配置信息较多,系统用4个页签展示。本示例仅介绍部分涉及到的参数,完整的参数说明,请参见管理API。
属性配置
名词
名词解释
API名称(必选)
数据API的名称,支持汉字,英文,数字,下划线(_),且只能以英文和汉字开头,4~100个字符。
本示例的API名称为
POC_API_test
。路径(必选)
该路径为API调用地址的组成部分。
路径只能以
/
开头,只支持英文、数字、下划线(_)、横杠(-),如/item/add
。API调用地址的结构为:
https://{分组域名}{路径}
。如本示例的路径定义为
/item/POC_API_test
、分组域名为xxxx-cn-hangzhou.alicloudapi.com
,则最终API调用地址为https://xxxx-cn-hangzhou.alicloudapi.com/item/POC_API_test
。请求方式(必选)
通用的API请求方式,支持的选项:
POST
GET
本示例的请求方式为GET。
执行配置
本示例的执行配置为单实例查询的表引导模式,并设置
student_id
字段为请求参数,student_id
、course_id
、score
字段为返回参数。名词
名词解释
实例查询类型
实例查询的类型,支持的权限:
单实例查询:仅查询一个数据库实例。可以通过表引导模式和SQL脚本模式定义API。
跨实例查询:通过编写跨数据库查询DSQL,来实现多个不同实例数据的关联查询,详细信息,请参见官方文档。仅支持SQL脚本模式定义API。
数据源
待查询的数据库。通过输入关键字,可查询当前用户有查询权限的数据库。
该参数仅当实例查询类型为单实例查询模式时显示。
配置方式
选择API的配置方式,支持的选项:
表引导模式:通过可视化的方式选择表、字段,定义API的数据查询配置。
脚本模式:通过手动编写SQL脚本+变量的方式来定义API的数据查询配置。
说明从表引导模式切换为脚本模式时,系统将提示切换模式将清空请求参数和返回参数。
该参数仅当实例查询类型为单实例查询模式时显示。
选择表
表引导模式下,可选择需要执行查询的表。可通过输入关键字快捷查找表。
该参数仅当配置方式为表引导模式时显示。
字段列表
该字段列表会展示当前选择的数据表中的所有字段,您可以通过勾选的方式,快速定义目标字段作为API的请求参数和返回参数。
该参数仅当配置方式为表引导模式时显示。
请求参数
名词
名词解释
参数名称
调用API时的入参名称,支持英文、数字、下划线(_)、横杠(-),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。
变量名称或字段名称
这里显示该参数来源,可来源于表引导模式的字段,也可来源于脚本模式的变量。
数据类型
包括字符串、整型、浮点三种基本类型,默认为字符串。本示例将
student_id
参数的数据类型设置为整型。此参数的作用为:在调用时将校验请求参数值是否符合对应的类型,且在执行API时,保障SQL的正常执行。
返回参数
名词
名词解释
参数名称
返回参数名称,支持英文、数字、横杠(-)、下划线(_),且只能以英文或下划线(_)开头,1~50个字符,默认为字段名。
变量名称或字段名称
仅显示返回的字段名。
数据类型
包括字符串、整型、浮点三种基本类型,默认为字符串。
此参数的作用为:系统把查询后的数据,按照此处定义进行数据转换,最终将数据写入返回的JSON中。
配置完成后,单击发布按钮。
说明您也可以单击保存按钮,保存该API的配置。
至此,已发布该API接口。
步骤二:测试API
验证API配置是否正确。
- 登录数据管理DMS 5.0。
在顶部菜单栏中,选择 。
说明若您使用的是极简模式的控制台,请单击控制台左上角的图标,选择
。在左侧导航栏,单击API测试。
在下拉框中,选择
POC_API_test
。在参数值文本框中。输入
1
,单击测试按钮。执行后,右侧会显示执行信息以及执行的返回结果(以表格和JSON两种方式呈现)。
步骤三:调用API
您可以通过多种方式调用API,例如使用SDK调用API和客户端调用API,调用时认证方式包括简单认证(AppCode)和摘要签名认证方式。具体操作,请参见API调用概述。
本示例介绍使用简单认证(AppCode)方式调用API。API调用地址的结构为:https://{Endpoint}{API路径}?AppCode=AppCode值&请求参数1=xxx&请求参数2=xxx
。您可以在DMS控制台上获取Endpoint
、AppCode值
等信息。
- 登录数据管理DMS 5.0。
在顶部菜单栏中,选择 。
说明若您使用的是极简模式的控制台,请单击控制台左上角的图标,选择
。在左侧导航栏,单击API调用。
在API调用页面,获取
Endpoint
与AppCode值。本示例的API调用地址为:
https://xxxe3e-cn-hangzhou.alicloudapi.com/item/POC_API_test?AppCode=3284xxxxx&student_id=1
您可以将API调用地址复制到浏览器或通过curl命令调用该API。